home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / BASIC / LIB / EVENTSHELL / DOCS / Manual-F < prev    next >
Text File  |  1996-05-18  |  68KB  |  1,816 lines
  1.  
  2.  
  3.  
  4.  
  5.     CONTENTS
  6.  
  7.  
  8.  
  9.     1. Introduction........................................................1
  10.     2. Creating An Example Application.....................................1
  11.     3. A Tutorial..........................................................2
  12.     4. General Overview....................................................5
  13.     5. The Tools..........................................................19
  14.     6. Distributing EvntShell Applications................................21
  15.     7. Debugging..........................................................21
  16.     8. The Credits........................................................21
  17.     9. Future Enhancements................................................22
  18.     10. Change History....................................................22
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.     
  71.  
  72.  
  73.  
  74.     EvntShell 2
  75.     ________________________________________________________________________
  76.  
  77.  
  78.     1. Introduction
  79.     ———————————————
  80.          
  81.     A 'Shell' program is a starting point for developing your own
  82.     applications that run under the RISC-OS wimp system. The EvntShell
  83.     library contains code to handle most of the 'Events' (i.e. opening a
  84.     menu, closing a window etc) that can occur, and all your application
  85.     has to do is inform the library what it should do when certain events
  86.     occur. For example a menu can be attached to a window or to an icon -
  87.     the library will open the menu for you (in the correct position!) when
  88.     the <MENU> button on the mouse is used.
  89.  
  90.     PROCshell_AttachModeChangeHandler is another very simple example which
  91.     calls a function in the 'User Application' (this is the bit you write,
  92.     starting with a 'Shell' created by the AppBuild tool or by modifying
  93.     one of the examples) when the screen mode changes. A more complicated
  94.     example is PROCshell_AttachPane which allows the attachment of pane
  95.     windows to a parent window. All opening and closing of windows and
  96.     panes is handled totally by the library code.
  97.  
  98.     Normally writing a wimp application is a very complex business,
  99.     involving much reading of the Programmers Reference Manuals, magazine
  100.     articles and examining other applications. The aim of the EvntShell
  101.     library is to reduce the need for this and to enable the speedy
  102.     creation of easily maintained and robust applications.
  103.  
  104.     Another important reason for using this Shell is that it attempts to
  105.     ensure that any application written using it follows the RISC OS 3
  106.     Style Guide which defines how applications should look and behave. For
  107.     example menus attached to icons ('popup' menus) appear to the right of
  108.     the icon they are attached to and the mouse pointer is repositioned
  109.     appropriately. Implementing the Style Guide recommendations is not easy
  110.     and at the moment very few of the necessary changes to the library code
  111.     have been made, however, this will improve in future releases.
  112.  
  113.     In order to use the library it is necessary to have a reasonable
  114.     understanding of how to use an Archimedes and the programs supplied
  115.     with it. Some experience in BASIC is also of course required. This
  116.     manual does not cover how to use tools like the Template editor which
  117.     has its own instructions and may not have been supplied with your copy
  118.     of the EvntShell library.
  119.  
  120.     2. Creating An Example Application
  121.     ——————————————————————————————————
  122.  
  123.     The easiest way to create a new application is to use the AppBuild
  124.     tool. Run this and drag the application icon from the AppBuild window
  125.     to a directory display. The various options available using AppBuild
  126.     will be discussed later, but for now just quit AppBuild and run the
  127.     newly created application. You should see a blank icon appear on the
  128.     icon bar and clicking <MENU> over this will bring up the usual icon bar
  129.     menu including the items 'Info' and 'Quit'. 'Info' leads to the normal
  130.     'About This Program' window (the icons of which are blank at the
  131.     moment) and 'Quit' which stops the application and removes it from the
  132.  
  133.  
  134.  
  135.  
  136.                                     Page 1
  137.  
  138.  
  139.  
  140.     
  141.  
  142.  
  143.  
  144.     EvntShell 2
  145.     ________________________________________________________________________
  146.  
  147.  
  148.     icon bar - don't quit it just yet.
  149.  
  150.     Clicking <SELECT> on the iconbar icon will open a window which has the
  151.     usual controls and may be scrolled and moved around the screen. Keep
  152.     the application you have just created handy as in the next section
  153.     we'll look at the program code and see how to change it to suit your
  154.     own needs.
  155.       
  156.     As you can see it is very easy to create a new shell application - even
  157.     if this particular one doesn't do anything useful yet!
  158.  
  159.     3. A Tutorial
  160.     —————————————
  161.  
  162.     The first few lines of any EvntShell program initialise the memory
  163.     management, set up error handlers and load any resources (templates,
  164.     message files, sprites etc) required by the program.
  165.     This code should not need editing. PROCapp_init determines what happens
  166.     when the application starts, in this case an iconbar icon is created 
  167.     and various 'events' are attached to it. The code created by !AppBuild
  168.     is as shown below, although the REMs have been added for this manual.
  169.     Try defining other windows and menus and see what happens.
  170.  
  171.  
  172.     DEF PROCapp_init
  173.     PROCSetUp_Menus   :REM set up iconbar menu
  174.     PROCSetUp_Windows :REM set up main window
  175.     PROCSetUp_IconBar :REM put icon on the iconbar and attach events
  176.     ENDPROC 
  177.     :
  178.     REM ===== Menu_Setup routines ===================================
  179.  
  180.     DEF PROCSetUp_Menus
  181.     LOCAL void%
  182.     REM Construct the iconbar menu..
  183.     MenuHandle_IconBar% = FNshell_MenuNew( "NewApp", "Menu_IBar", 2 )
  184.     MenuItem_Info%      = FNshell_MenuAdd( 0, "Info", "" )
  185.     void%               = FNshell_MenuAdd( 0, "Quit", "_MenuSelect_Quit" )
  186.     REM Attach the 'About this program' dialog box to the 'Info'
  187.     REM item of the menu. Call FN_PreOpenInfo before opening it so
  188.     REM that the icons can be filled in, don't call a FN after
  189.     REM opening it.
  190.     PROCshell_AttachMenuDBox( MenuItem_Info%, "progInfo",
  191.     "_PreOpenInfo", "" )
  192.     ENDPROC
  193.     :
  194.  
  195.     REM ===== Window_SetUp routines =================================
  196.  
  197.     DEF PROCSetUp_Windows
  198.     REM create a window from the template called 'mainw', place the
  199.     REM window handle in mainw%
  200.     PROCshell_CreateWindowStatic( "mainw", mainw% )
  201.     ENDPROC
  202.  
  203.  
  204.  
  205.  
  206.                                     Page 2
  207.  
  208.  
  209.  
  210.     
  211.  
  212.  
  213.  
  214.     EvntShell 2
  215.     ________________________________________________________________________
  216.  
  217.  
  218.     :
  219.  
  220.     REM ===== IconBar_SetUp routines ================================
  221.  
  222.     DEF PROCSetUp_IconBar
  223.     REM sicon is the handle of the icon. -1 means right side of
  224.     REM iconbar, -2 would be left side. The name of the sprite for
  225.     REM the icon is the same as the application directory. A menu
  226.     REM with the handle 'MenuHandle_IconBar%' is attached.
  227.     sicon=FNshell_Iconbar(-1,"!"+FNshell_GetAppName,"",120,
  228.     MenuHandle_IconBar%,0,0,0)
  229.     REM attach a help tag for the icon, this will send the text
  230.     REM following 'iconbar:' to the !Help application. See the
  231.     REM 'Messages' file for this.
  232.     PROCshell_AttachHelpTag(-1,sicon,"iconbar")
  233.     REM lastly attach the clickselect event. When <SELECT> is
  234.     REM clicked over the icon call FN_clickiconbar
  235.     PROCshell_AttachClickSelect(-1,sicon,"_ClickSelect_IconBar")
  236.     ENDPROC
  237.     :
  238.  
  239.     REM ===== Dialog_PreOpen routines ===============================
  240.  
  241.     DEF FN_PreOpenInfo(h%)
  242.     REM fill in icons. Try editing the 'Messages' file to make text
  243.     REM appear in the icons (just add the text after progInfo0: etc).
  244.     REM h% is the handle of the window.
  245.     PROCshell_IconPutData(h%,0,FNshell_MessageNoArgs("progInfo0"),0)
  246.     PROCshell_IconPutData(h%,1,FNshell_MessageNoArgs("progInfo1"),0)
  247.     PROCshell_IconPutData(h%,2,FNshell_MessageNoArgs("progInfo2"),0)
  248.     PROCshell_IconPutData(h%,3,FNshell_MessageNoArgs("progInfo3"),0)
  249.     =0
  250.     :
  251.  
  252.     REM ===== Dialog_PostOpen routines ==============================
  253.  
  254.     REM ===== Click_Select routines =================================
  255.  
  256.     DEF FN_ClickSelect_IconBar(wh%,icon%)
  257.     REM open the window with the handle mainw% when a click of
  258.     REM <SELECT> is received on the iconbar icon. wh% is the handle
  259.     REM of the window over which the click occured (the iconbar) and
  260.     REM icon% is the handle of the iconbar icon
  261.     PROCshell_OpenWindowStatic(mainw%)
  262.     =0
  263.     :
  264.  
  265.     REM ===== Menu_Select routines ==================================
  266.  
  267.     DEF FN_MenuSelect_Quit(blk%)
  268.     _closedown%=TRUE
  269.     =0
  270.     :
  271.  
  272.  
  273.  
  274.  
  275.  
  276.                                     Page 3
  277.  
  278.  
  279.  
  280.     
  281.  
  282.  
  283.  
  284.     EvntShell 2
  285.     ________________________________________________________________________
  286.  
  287.  
  288.     REM ===== Menu_Warning routines =================================
  289.  
  290.     REM ===== Data_Load routines ====================================
  291.  
  292.     REM ===== Data_Save routines ====================================
  293.  
  294.  
  295.     Let us now look at how events should be attached to a window. It is
  296.     important to always do this just before the window opens (i.e. in the
  297.     PreOpen routine) because a static window and a dynamic window can be
  298.     created from the same template but they will of course have different
  299.     handles. The following example shows how this should be handled (we are
  300.     assuming the template in question is called 'xfer' and the program is
  301.     called 'MyApp').
  302.  
  303.  
  304.     DEF PROCapp_init
  305.     ...
  306.     PROCSetUp_Windows
  307.     PROCSetUp_Menus
  308.     PROCshell_AttachHotKey("F3",FALSE,FALSE,FALSE,"",xfer%,"_PreOpen_Xfer","
  309.     ")
  310.     ...
  311.     ENDPROC
  312.     :
  313.     DEF PROCSetUp_Windows
  314.     ...
  315.     PROCshell_CreateWindowStatic("xfer",xfer%)
  316.     ...
  317.     ENDPROC
  318.     :
  319.     DEF PROCSetUp_Menus
  320.     ...
  321.     MenuHandle_IconBar%=FNshell_MenuNew("MyApp")
  322.     MenuItem_Save%     =FNshell_MenuAdd(0,"Save","")
  323.     PROCshell_AttachMenuDBox(MenuItem_Save%,"xfer","_PreOpen_Xfer",
  324.     "_PostOpen_Xfer")
  325.     ...
  326.     ENDPROC
  327.     :
  328.     DEF FN_PreOpen_Xfer(h%)
  329.     ...
  330.     REM OK icon is 0, Filename icon is 2, File icon is 3, Filetype is &344..
  331.     PROCshell_IconPutData(h%,2,filename$),FALSE)
  332.     PROCshell_AttachDataSave(h%,3,100,&344,2,"_DataSave_Xfer")
  333.     PROCshell_AttachClickSelect(h%,0,"_ClickSelect_XferOK")
  334.     ...
  335.     =0
  336.     :
  337.     DEF FN_PostOpen_Xfer(h%)
  338.     ...
  339.     PROCshell_WindowCentreOnPointer(h%)
  340.     ...
  341.     =0
  342.  
  343.  
  344.  
  345.  
  346.                                     Page 4
  347.  
  348.  
  349.  
  350.     
  351.  
  352.  
  353.  
  354.     EvntShell 2
  355.     ________________________________________________________________________
  356.  
  357.  
  358.     :
  359.  
  360.  
  361.     The xfer window will open when F3 is pressed (assuming one of the open
  362.     windows has the 'grab hot keys' bit set) and also when the sub menu on
  363.     the 'Save' menu item is opened. In each case FN_PreOpen_Xfer will be
  364.     called to attach the events and fill in the filename icon.
  365.      
  366.     4. General Overview
  367.     ———————————————————
  368.  
  369.     This section explains the various elements of an application using the
  370.     EvntShell library, and any limitations and assumptions made by me.
  371.  
  372.     4.1 Dynamic Windows
  373.  
  374.     Dynamic windows are those created by moving the pointer over a submenu
  375.     pointer arrow (i.e the normal 'About this program' window produced by
  376.     the 'Info' entry on the iconbar menu) or optionally when a 'hot key' is
  377.     pressed (for example F3 in most applications opens a save box). They
  378.     are opened with a call to PROCshell_OpenWindowDynamic.
  379.  
  380.     When writable icons exist in the dynamic window up/down cursor and
  381.     TAB/SHIFT TAB keypresses move the caret between the icons using the
  382.     icon handles to determine where to move next. You should ensure
  383.     therefore that the order of the icon handles is a logical progression
  384.     through the dialog box. Icons which are unselectable (i.e. greyed out)
  385.     will be ignored. Pressing the <RETURN> key causes icon 0 to be pressed
  386.     (normally a 'default action' icon with an extra border) and the
  387.     menu/dialog box to be closed.  Actually clicking <SELECT> on icon 0 of
  388.     a dynamic dialog box will cause the shell library to close the window
  389.     as well.
  390.  
  391.     When a 'hot key' is pressed you have the option of opening  a dynamic
  392.     dialog box which will disappear when a mouse click is made outside it
  393.     or the <ESC> key is pressed, or as a 'Static' dialog box which must be
  394.     explicitly closed by the  user application program.
  395.  
  396.     Do not attempt to close a dynamic dialog box with a call to
  397.     PROCshell_CloseWindow or PROCshell_DeleteWindow as this will cause an
  398.     error when the shell library tries to close or delete the window.
  399.  
  400.     All windows used by the user application are assumed to be defined in
  401.     the 'Templates' file and edited using FormEd or one of the Public
  402.     Domain/ShareWare equivalents.
  403.  
  404.     4.2 Static Windows
  405.  
  406.     These are opened with a call to PROCshell_OpenWindowStatic and respond
  407.     to cursor,TAB and <RETURN> keypresses like dynamic dialog boxes except
  408.     that pressing <RETURN>  will not close the window. Static windows must
  409.     be created with a call to PROCshell_CreateWindowStatic.
  410.  
  411.     Closing these windows is the responsibility of the  application program
  412.  
  413.  
  414.  
  415.  
  416.                                     Page 5
  417.  
  418.  
  419.  
  420.     
  421.  
  422.  
  423.  
  424.     EvntShell 2
  425.     ________________________________________________________________________
  426.  
  427.  
  428.     (use PROCshell_CloseWindow) except in the case of a click on the
  429.     'Close' icon in the title bar icon (if present).
  430.  
  431.     You would use a static window for the main window of an application, or
  432.     perhaps for a save box as in the case of the !WinSave2 example. The
  433.     advantage of using a static window in  this case is that this allows
  434.     the user to open directory  viewers or start other applications while
  435.     keeping the save  box on the screen.
  436.  
  437.     4.3 Resources
  438.  
  439.     'Resources' is a general term for additional files needed by an
  440.     application. There will (almost) always be some of these, such as
  441.     sprite files. Others, for example message files may not be required.
  442.  
  443.     The EvntShell library now supports ResFind which allows the selection
  444.     of the desired language for message files etc much easier. Briefly
  445.     explained it checks the currently configured language of the computer
  446.     it is running on and sets up a path to the resource files. This would
  447.     normally be <App$Dir>.Resources.UK for a UK configured computer, or
  448.     <App$Dir>.Resources.Germany for a German one. This is handled for you
  449.     if you use !AppBuild to create the application.
  450.  
  451.     AppBuild now offers to place the resources in the appropriate
  452.     directories for you when you create a new application, and to place a
  453.     call to ResFind in the !Run file.
  454.  
  455.     Using ResFind is optional and EvntShell applications will function
  456.     equally well if you don't use it. It does make the production of
  457.     applications that can be easily used in any country much easier,
  458.     however, and this should be encouraged. Most of the programming tools
  459.     and modules used during the development of this library were written
  460.     outside the UK.
  461.  
  462.     The author would appreciate help in translating the ShellMsgs file and
  463.     the documentation into other languages.
  464.  
  465.     The full ResFind documentation supplied with the library contains
  466.     further details on how it works and the advantages to be gained by
  467.     using it. As a taster, here is the part of the documentation intended
  468.     to be distributed with applications using ResFind.
  469.  
  470.     (Base for the application's documentation - please replace <ProgName>
  471.     by the name of your application without the !)
  472.  
  473.     !<ProgName> adapts automatically to the configured language if the
  474.     corresponding messages etc. are available. For this purpose a Resources
  475.     directory is contained in the application in which a subdirectory for
  476.     each language supported resides. If the language you need isn't in
  477.     there, please feel free to duplicate any of these language directories
  478.     and translate the contents.
  479.  
  480.     When you run the program a utility called ResFind is called which reads
  481.     the language your computer is configured to and then looks for the
  482.  
  483.  
  484.  
  485.  
  486.                                     Page 6
  487.  
  488.  
  489.  
  490.     
  491.  
  492.  
  493.  
  494.     EvntShell 2
  495.     ________________________________________________________________________
  496.  
  497.  
  498.     corresponding language directory. If this fails the program will run in
  499.     English (UK). By setting several system variables (best done in your
  500.     system's !Boot file) you can change the language looked for. With this
  501.     you can make sure a program runs in a certain language, e.g. to avoid a
  502.     weird translation. Furthermore it is possible to name several languages
  503.     you prefer to English.
  504.  
  505.     This is controlled by three system variables:
  506.  
  507.       <ProgName>$Language, ResFind$LanguagesPref and ResFind$Languages$Suff.
  508.  
  509.     When running the application ResFind looks for the first language
  510.     supported along the following list of languages:
  511.  
  512.      1. Contents of the variable <ProgName>$Language
  513.      2. Contents of the variable ResFind$LanguagesPref
  514.      3. The configured language
  515.      4. Contents of the variable ResFind$LanguagesSuff
  516.      5. UK
  517.  
  518.     Take a Norwegian user for example (lots of great programs come from
  519.     there) whose computer is configured to 'Norway'. Since this language
  520.     isn't too common in Europe most programs won't support it - except for
  521.     Norwegian ones. But our user is pretty good in German and French but
  522.     not too fond of English. Therefore he prefers these languages to UK and
  523.     would thus put the following line in his system's !Boot file:
  524.  
  525.       *Set ResFind$LanguagesSuff Germany,France
  526.  
  527.     Running an applications (such as this one) using ResFind the list of
  528.     languages looked for is 'Norway,Germany,France,UK'.
  529.  
  530.     In case this user has an application called !Pete supporting the
  531.     language 'Humorous' the line:
  532.  
  533.       *Set Pete$Language Humor
  534.  
  535.     in the !Boot file makes sure !Pete will run humorous.
  536.  
  537.     A brief description of the various resource files follows.
  538.  
  539.     4.3.1 Templates
  540.  
  541.     All windows used by programs based on the shell library would normally 
  542.     be defined using a template editor as this is far simpler than 
  543.     creating the windows/icons in the user program. This is not as
  544.     inflexible as it may sound as windows and icons can be resized, moved
  545.     or otherwise altered by shell library routines.
  546.  
  547.     The template file must be called 'Templates' and be either in the
  548.     application directory or in the appropriate language directory if
  549.     ResFind is in use. Note that if you are using different templates for
  550.     different languages you must use ResFind. In most cases, however, it is
  551.     sufficient to have only one template file in the application directory
  552.  
  553.  
  554.  
  555.  
  556.                                     Page 7
  557.  
  558.  
  559.  
  560.     
  561.  
  562.  
  563.  
  564.     EvntShell 2
  565.     ________________________________________________________________________
  566.  
  567.  
  568.     and to insert the text taken from the message file in the language of
  569.     choice into the icons.
  570.  
  571.     A call to PROCshell_ResourcesInit will find the template file and load
  572.     all the templates it contains allocating memory as required.
  573.  
  574.     4.3.2 Sprites
  575.  
  576.     The sprite file must be called 'Sprites' and be either in the
  577.     application directory or in the appropriate language directory if
  578.     ResFind is in use. A call to PROCshell_ResourcesInit will find the file
  579.     if it exists and load all the sprites it contains allocating memory as
  580.     required.
  581.  
  582.     Optionally a second sprite file called 'Sprites22' containing high
  583.     resolution sprites for users with multisync monitors may be present. If
  584.     the application is started in a high resolution screen mode and
  585.     'Sprites22' is available it will be loaded instead of 'Sprites'.
  586.  
  587.     The sprite area pointer for each loaded template will be set to point
  588.     to the user sprite area, which put simply this means that all sprites
  589.     displayed in windows must be present in the 'Sprites' and 'Sprites22'
  590.     files. This may, however, be changed after loading with a call to
  591.     FNshell_WindowSetSpriteArea.
  592.          
  593.     4.3.3 Message Files
  594.  
  595.     The message file is a normal ASCII file written using !Edit or similar
  596.     that contains message strings preceeded by a message tag. The
  597.     application program should find the messages as required by tag name
  598.     which allows the production of foreign language versions (probably by
  599.     someone else!). It is also far easier to edit the message file to
  600.     change text displayed by the application than using !FormEd or similar.
  601.  
  602.     The !Run file of the user application automatically loads a support
  603.     module 'MsgTrans' if required (it is built in to RISC OS 3) to provide
  604.     this facility.
  605.  
  606.     The message file must be called 'Messages' and be in the application
  607.     directory or in the appropriate language directory if ResFind is in
  608.     use. A call to PROCshell_ResourcesInit will find the file if it exists
  609.     and load all the messages it contains allocating memory as required.
  610.  
  611.     The messages issued by the library code are stored in a file called
  612.     'ShellMsgs' inside the !EvntShell.Resources.UK directory. If this file
  613.     is present in the user application directory (or the application
  614.     Resources directory) then it is loaded from there, if not it is loaded
  615.     from !EvntShell. This is to aid the construction of stand alone
  616.     applications.
  617.  
  618.     4.3.4 Modules
  619.  
  620.     Various Public Domain modules are used by the EvntShell library, these
  621.     are stored in the !EvntShell application and loaded as required. A full
  622.  
  623.  
  624.  
  625.  
  626.                                     Page 8
  627.  
  628.  
  629.  
  630.     
  631.  
  632.  
  633.  
  634.     EvntShell 2
  635.     ________________________________________________________________________
  636.  
  637.  
  638.     list is:
  639.  
  640.  
  641.     Interface   - 3D icon effects, changing pointer shapes etc
  642.     MenuUtils   - menu handling
  643.     FontMenu    - font menu handling
  644.     MsgTrans    - message files (supplied for Risc-OS 2
  645.                   compatability)
  646.     FontWindow  - handling outline fonts across mode changes (not
  647.                   used at the moment)
  648.     DrawFile    - used for rendering drawfiles (this module is
  649.                   copyright Acorn)
  650.  
  651.  
  652.     Note that in general no documentation is supplied for these modules, it
  653.     is all available elsewhere (or why not write to the author?)
  654.  
  655.     The EvntShell library makes the assumption that the interface module
  656.     will always be used. The reason is that firstly that it is highly
  657.     likely that some other PD program will have already loaded it, and
  658.     secondly that the facilities it provides for changing pointer shapes
  659.     over certain icons is extremely useful as a prompt for what the icon is
  660.     for. Indeed RISC-OS 3 has this built in so even Acorn are supporting 3D
  661.     buttons etc....
  662.  
  663.     The module is loaded by the !Run file if not already loaded. Using a
  664.     template editor that is 'Interface Aware' makes incorporating these
  665.     effects into a user program easy as once the icons have been designed
  666.     and placed the shell library handles all the redrawing automatically.
  667.  
  668.     Note that windows containing 3d interface icons must have the 'Auto
  669.     Redraw' flag off, but if the template editor displays interface icons
  670.     then the user application will as well.
  671.  
  672.     4.4 Menus
  673.  
  674.     Menus are now handled by MenuUtils which was written by Alex Petrov.
  675.     Versions of the library prior to 1.20 used a menu editor to create a
  676.     seperate menu template file, but I have now abandoned this as it was
  677.     rather inflexible.
  678.  
  679.     The use of MenuUtils has enabled me to remove large chunks of slow
  680.     BASIC code and to provide many more features, such as creation and
  681.     modification of menus under program control. The menus themselves
  682.     appear more quickly as well (OK Cy?).
  683.  
  684.     Menus may be created by calling functions in the user application, or
  685.     from a menu command file. The file option is especially useful for
  686.     lists of items that can be edited by the user - for example the new
  687.     version of !VideoBase uses menu command files for lists of commonly
  688.     used categories of recordings (Documentary, Action Film etc) a menu of
  689.     which can be attached to an icon for easy access. As the command file
  690.     is a simple text file it is very easy to edit to meet special
  691.     requirements.
  692.  
  693.  
  694.  
  695.  
  696.                                     Page 9
  697.  
  698.  
  699.  
  700.     
  701.  
  702.  
  703.  
  704.     EvntShell 2
  705.     ________________________________________________________________________
  706.  
  707.  
  708.  
  709.     A demonstration application !TestMenu should have been supplied with
  710.     the library code so that you can try out some of the possibilities
  711.     yourself.
  712.  
  713.     The appearance of the RISC OS 3 Style Guide has caused a few changes in
  714.     the way that EvntShell handles 'popup' menus (menus attached to icons
  715.     in windows other than the iconbar). Firstly they appear to the right of
  716.     the icon they are attached to, the mouse pointer also moving to the
  717.     recommended position, and secondly only SELECT and MENU will call up a
  718.     popup menu.
  719.  
  720.     Note that menus can only be attached to icons in static windows,
  721.     because as far as RISC OS is concerned a dynamic window is a menu.
  722.  
  723.     The  support module is  automatically loaded by the !Run file to
  724.     provide the new menu handling SWIs used by the EvntShell library.
  725.  
  726.     4.5 Saving Files
  727.  
  728.     This is achieved by a call to PROCshell_AttachDataSave which specifies
  729.     which filetype the saved file should be given, the name of a function
  730.     which will actually perform the save and the window/icon handles the
  731.     drag save event is associated with. It is therefore possible to have
  732.     different drag save events attached to different icons in the same
  733.     window. This is useful where it is possible to save the file as more
  734.     than one type - you can have multiple filetype icons in the save window.
  735.  
  736.     PROCshell_AttachDataSave also performs some checking when it is called.
  737.     For example an error message is generated if the file icon is not a
  738.     sprite icon. The button type of the file icon is also changed to
  739.     Click/Drag to avoid the need to get this correct when editing the
  740.     template file.
  741.  
  742.     The EvntShell library supports RAM file transfer for speed when saving
  743.     data to consenting applications.
  744.  
  745.     See the !WinSave2 and !VBase2 example applications for how to use this
  746.     routine.
  747.  
  748.     4.6 Loading Files
  749.  
  750.     This is achieved by a call to PROCshell_AttachDataLoad which tells the
  751.     EvntShell library which filetypes the user application is interested in
  752.     and the name of a function to call when a load event occurs. Multiple
  753.     files may be loaded, but in the current release of the library it is up
  754.     to the user application to keep track of where they are loaded and if
  755.     they have been modified. This will change in a future release.
  756.  
  757.     When the event is attached a check is made to see if the application
  758.     was started by double clicking a file which 'belongs' to it. If the
  759.     filetypes match then the file is loaded as if it had been dragged to
  760.     the icon bar icon. A filetype is associated with an application by the
  761.     inclusion of the line:
  762.  
  763.  
  764.  
  765.  
  766.                                     Page 10
  767.  
  768.  
  769.  
  770.     
  771.  
  772.  
  773.  
  774.     EvntShell 2
  775.     ________________________________________________________________________
  776.  
  777.  
  778.  
  779.       Set Alias$@RunType_xxx Run <Obey$Dir>.!Run %%*0
  780.  
  781.     where xxx is the filetype number.
  782.  
  783.     If required the files can be loaded automatically into a reserved block
  784.     of memory, or the user application can have total control over loading
  785.     and processing the file.
  786.  
  787.     The EvntShell library supports RAM file transfer for speed when loading
  788.     data from consenting applications.
  789.  
  790.     It is also possible to arrange for the user application to respond to a
  791.     range of filetypes by attaching more than one handler.
  792.  
  793.     An example application !DataLoad should have been included with the
  794.     Library to demonstrate how to do this.
  795.  
  796.     This is the code from !DataLoad used to achieve the load :
  797.  
  798.     PROCshell_AttachDataLoad(mainw%,0,&FEC,"_dataloadFEC",TRUE)
  799.  
  800.     The first parameter, mainw% is the wimp window handle, the second is
  801.     the icon handle. &FEC is the filetype to respond to and '_dataloadFEC'
  802.     is the name of the function to call to actually load the file. The last
  803.     parameter is TRUE to load the file automatically into a reserved block
  804.     of memory or FALSE  if you want to handle the loading yourself. In this
  805.     case loading is automatic and the loading function is simply:
  806.  
  807.     DEF FN_dataloadFEC(loc%,type%,name$,file_size%)
  808.     void%=FNshell_MessageWindow("File '"+name$+"'",0,"DataLoad","")
  809.     =0
  810.  
  811.     The data file (of type &FEC, template)  has been loaded at location
  812.     loc%, its type is in type% and  the full path name of the file is in
  813.     name$. All the function itself does is call  another function to
  814.     display a message window so that you can see that loading the file has
  815.     worked. This is a useful debugging technique!
  816.  
  817.     This method of loading a file works well for datafiles that are stored
  818.     as one continuous block of data such as a text file which will be
  819.     processed in some way. Suppose, however, you have a simple database
  820.     type application which needs to load data into BASIC arrays. In this
  821.     case you would simply use (assuming now the filetype is &205):
  822.  
  823.     PROCshell_AttachDataLoad(mainw%,0,&205,"_dataload205",FALSE)
  824.  
  825.     FN_dataload205 receives the full pathname of the file which has been
  826.     dragged to icon 0 (providing the filetype of the file was &205,
  827.     otherwise the load will be ignored) which may now be opened and the
  828.     data loaded as usual. If the 'no load' flag was set for this load event
  829.     and the load was from another application the data is saved in a file
  830.     called 'ScrapFile' in the user application directory.
  831.  
  832.  
  833.  
  834.  
  835.  
  836.                                     Page 11
  837.  
  838.  
  839.  
  840.     
  841.  
  842.  
  843.  
  844.     EvntShell 2
  845.     ________________________________________________________________________
  846.  
  847.  
  848.     4.7 Compressing EvntShell Applications
  849.  
  850.     Due to the complex nature of the library code and the desire for it to
  851.     do as much as possible to make a user application easy to write the
  852.     ShellLibRT library file has expanded to around 150K. This is obviously
  853.     undesirable especially if you are planning to send your finished
  854.     program to a PD library. If you want people to be able to read your
  855.     source code you can use the 'RunTime' version of the library which has
  856.     been mildly compressed, but for the smallest possible program it is
  857.     necessary to append the library (either version) to the end of the user
  858.     application, remove the line which loads the library file and run the
  859.     whole lot through a BASIC program compressor.
  860.  
  861.     I recommend !BasShrink or !Shrink_PD (the Public Domain version of
  862.     !BasShrink) by John Wallace although John's program is slow and not
  863.     presently multitasking it does produce code that still runs! This is
  864.     unfortunately not true of Cy Booker's otherwise superb !BC which will
  865.     not work on the EvntShell library. However, if I or Cy can find out
  866.     what the problem is we'll fix it.
  867.  
  868.     Future versions of !BasShrink should be able to remove unused routines
  869.     to save even more space, or alternatively BLibII can be used to
  870.     pre-process the application to link in only the routines that are
  871.     actually used. See the manual section 'Other Tools' for more details.
  872.  
  873.     There is one important point to bear in mind when using the shell
  874.     library and !BasShrink together - function names that are EVALuated by
  875.     the shell library should begin with a '_' character and the 'Preserve
  876.     names starting with' radio button in the !BasShrink window must be ON.
  877.     In short if you are calling any
  878.     shell library routine that has a function name as a parameter then that
  879.     name must start with a '_'. Failure to observe this rule will result in
  880.     a non-working compressed program!
  881.  
  882.     Assuming you have !BasShrink 2.14 or later the EvntShell library can be
  883.     compressed with all switches on except 'Shorten FN names', 'Shorten
  884.     PROC names' and 'Remove * comments'. If you are not going to use
  885.     !BLibII you can switch on 'Remove * comments' to strip out the !BLibII
  886.     commands.
  887.  
  888.     If you append the EvntShell library to the user application manually or
  889.     by using BLibII you can compress the complete program with all switches
  890.     on.
  891.  
  892.     4.8 The RunTime Library
  893.  
  894.     This is a compressed version of the full library which should be used
  895.     wherever possible as it will load and run faster. The only reason for
  896.     using the uncompressed library would be to add extra debugging code or
  897.     perhaps to modify the routines. In this case, however, it is better to
  898.     just copy the uncompressed routine into the user application and edit
  899.     it there.
  900.  
  901.     The uncompressed version is called ShellLib, the compressed version is
  902.  
  903.  
  904.  
  905.  
  906.                                     Page 12
  907.  
  908.  
  909.  
  910.     
  911.  
  912.  
  913.  
  914.     EvntShell 2
  915.     ________________________________________________________________________
  916.  
  917.  
  918.     ShellLibRT. Both can be found inside the !EvntShell application
  919.     directory.
  920.  
  921.     The ShellLibRT file has had the BLibII commands stripped out to save
  922.     space.
  923.  
  924.     4.9 The !EvntShell Application
  925.  
  926.     As large chunks of code are common to all EvntShell applications it
  927.     makes sense to store it only once on the disk, hence !EvntShell which
  928.     should be treated like the !System application. If you have a hard disk
  929.     put it in the root directory (or ensure it is booted by your Boot
  930.     file). If you have a floppy only system put it on all your disks
  931.     (removing the ShellLib file and making sure all EvntShell applications
  932.     use ShellLibRT will help save disk space). The system message file and
  933.     various modules are also to be found here.
  934.  
  935.     The name '!EvntShell' has been registered with Acorn as an official
  936.     shared system resource.
  937.  
  938.     4.10 Handling Panes
  939.  
  940.     A pane window is a window attached to a parent window which has
  941.     different properties to the parent. A well-known example is the
  942.     'ToolBox' pane attached to a !Draw window which always appears at the
  943.     top left of the parent window however the parent window is scrolled.
  944.     Another example could be a parent window without scrollbars which has a
  945.     scrolling pane attached to the work area which might be used in a
  946.     'FindFile' application to display a list of finds.
  947.  
  948.     Panes are created using !FormEd or similar with the 'pane' flag set. A
  949.     call to PROCshell_AttachPane specifies which pane is attached to which
  950.     window and the position of the pane. Multiple panes may to attached to
  951.     a parent window (see the example application !Panes).
  952.  
  953.     The opening and closing of panes is handled totally by the shell
  954.     library - a call to PROCshell_OpenWindow after attaching the panes will
  955.     open the parent window and the panes together.
  956.  
  957.     It is normally necessary for certain bits in the window definition
  958.     block to be set up in a special way if a window is to be treated as a
  959.     pane. This is not required when using the EvntShell library as the act
  960.     of attaching the event makes the changes needed.
  961.  
  962.     You should avoid attaching a pane to a parent window where it is
  963.     possible to resize the parent in such a way that the pane lies outside
  964.     the window it is attached to. This will cause (non-fatal) problems when
  965.     the windows are redrawn. Most RISC OS programs also avoid this for the
  966.     same reasons.
  967.  
  968.     When attaching a pane it is possible to specify a 'pane flag' value
  969.     which determines where the pane will be attached and to some extent how
  970.     it will behave when the parent window is resized. The currently valid
  971.     pane flags are:
  972.  
  973.  
  974.  
  975.  
  976.                                     Page 13
  977.  
  978.  
  979.  
  980.     
  981.  
  982.  
  983.  
  984.     EvntShell 2
  985.     ________________________________________________________________________
  986.  
  987.  
  988.  
  989.       0 = attached to parent window work area
  990.       1 = attached to left edge outside parent
  991.       2 = attached to top edge
  992.       3 = attached to left edge inside parent
  993.       4 = attached to bottom edge
  994.       5 = attached to right edge
  995.  
  996.     In cases 1-5 the library will attempt to stretch the pane window so
  997.     that it will fill the whole width or depth of the parent window.
  998.  
  999.     4.11 Outline Fonts
  1000.  
  1001.     The EvntShell Library supports Outline Fonts in two ways at the moment.
  1002.     Firstly Joris Röling's FontMenu module is used to display a menu of all
  1003.     available fonts on the system, and secondly the window template loading
  1004.     routine allows icons and window titles to use fonts.
  1005.  
  1006.     Routines are provided to attach a font menu to an existing menu as a
  1007.     submenu (PROCshell_AttachFontSubMenu), or to open the font menu as a
  1008.     menu in its own right (PROCshell_AttachFontMenu). If the user makes a
  1009.     valid font selection the font name can be retrieved (with
  1010.     FNshell_FontMenuGetLastSelectedFont) for use in the user application.
  1011.     Changes to the Font$Path variable such as adding or removing font
  1012.     directories are detected and the font menu rebuilt as necessary.
  1013.  
  1014.     It will not, however, detect fonts being added or removed from an
  1015.     existing font directory while the EvntShell application is running. It
  1016.     appears that a re-boot is required to sort things out after the
  1017.     contents of the font directories have changed. Oh well, it seems that a
  1018.     lot of other applications can't cope with this either!
  1019.  
  1020.     The FontMenu module creates a menu in the relocatable module area which
  1021.     is shared between all applications wishing to use it. As a font menu
  1022.     potentially takes up a lot of space this is a very efficient way of
  1023.     handling it, especially as the menu is laid out so that it is easier to
  1024.     use than a straight list of fonts.
  1025.  
  1026.     A help system containing the full FontMenu documentation is supplied
  1027.     with the EvntShell library as it is a requirement that the the module
  1028.     and its documentation must be supplied together. However, it is
  1029.     unlikely that the SWIs provided by the module will need to be called by
  1030.     the user application as the library code performs the necessary actions.
  1031.  
  1032.     The example application !Redraw demonstrates the use of these routines.
  1033.  
  1034.     4.12 Interactive Help
  1035.  
  1036.     The EvntShell library supports Acorn's Interactive Help application
  1037.     !Help by searching icon validation strings for the 'I' command (as
  1038.     recommended by the author of the Interface module) for a message tag.
  1039.  
  1040.     The message belonging to the tag will be looked up and sent to !Help
  1041.     (if !Help is running). An example would be a validation string of
  1042.  
  1043.  
  1044.  
  1045.  
  1046.                                     Page 14
  1047.  
  1048.  
  1049.  
  1050.     
  1051.  
  1052.  
  1053.  
  1054.     EvntShell 2
  1055.     ________________________________________________________________________
  1056.  
  1057.  
  1058.     "iMessTag01", where the file 'Messages' contains the line
  1059.     'MessTag01:This is a test'. 'This is a test' would be the message
  1060.     displayed.
  1061.  
  1062.     It is also possible to attach a message tag to a window or a
  1063.     window/icon using PROCshell_AttachHelpTag. A message tag is a string
  1064.     consisting of not more than 11 characters long and represents a message
  1065.     string to be found in the 'Messages'
  1066.     file.
  1067.  
  1068.     Interactive help can be enabled or disabled by calls to the EvntShell
  1069.     library. It is useful to offer the option to disable interactive help
  1070.     for experienced users as the applications response times will be
  1071.     improved.
  1072.  
  1073.     4.13 User Redraws
  1074.  
  1075.     4.13.1 Simple Cases
  1076.  
  1077.     By 'Simple Cases' I mean text, lines, arcs, filled shapes etc. In other
  1078.     words anything that it is easy for the program to redraw quickly - this
  1079.     excludes maps of the world and any kind of random display. For these
  1080.     cases it is much faster to redirect the screen output into a sprite
  1081.     (see the next section).
  1082.  
  1083.     Using the example application you created earlier (or create a new one
  1084.     using AppBuild) add the following line to PROCSetUp_Windows:
  1085.  
  1086.     PROCshell_AttachUserRedraw(mainw%,"_redraw")
  1087.  
  1088.     and add the following FN definition:
  1089.  
  1090.     DEF FN_redraw(blk%,x0%,y0%)
  1091.     REM set colour for circle - colours are numbered 0-15!
  1092.     REM draw the circle..
  1093.     SYS "Wimp_SetColour",11
  1094.     CIRCLE FILL x0%+200,y0%-200,120
  1095.     REM set colour for text...
  1096.     SYS "Wimp_SetColour",8 :REM colours are numbered 0-15!
  1097.     MOVE x0%+80,y0%-340:PRINT "This is an example of"
  1098.     MOVE x0%+40,y0%-380:PRINT "user drawn text and graphics"
  1099.     MOVE x0%+95,y0%-420:PRINT "in a desktop window"
  1100.     =0
  1101.  
  1102.     The routine that attaches the redraw event also alters the 'flags' of
  1103.     the window so that the 'Auto redraw' bit is set up correctly. When you
  1104.     run the application and open the main window now, a circle and some
  1105.     text will appear in the window. If another window is moved over this
  1106.     one, note that the window is correctly redrawn.
  1107.  
  1108.     The parameters x0% and y0% for the redraw routine are the coordinates
  1109.     of the top left corner of the window. Note that y coordinates are
  1110.     negative! Try experimenting with other drawing commands and putting
  1111.     text in different places in the window to get the hang of this.
  1112.  
  1113.  
  1114.  
  1115.  
  1116.                                     Page 15
  1117.  
  1118.  
  1119.  
  1120.     
  1121.  
  1122.  
  1123.  
  1124.     EvntShell 2
  1125.     ________________________________________________________________________
  1126.  
  1127.  
  1128.  
  1129.     4.13.2 Drawing Into A Sprite
  1130.  
  1131.     With a more complicated or random display you need to set up a sprite
  1132.     to draw into. The example application !Redraw2 shows how to do this.
  1133.  
  1134.     Note in this case that the display within the window is animated by
  1135.     calling the plotting routine at every null event received. There also
  1136.     has to be two redrawing routines, one called when you want the display
  1137.     redrawn and one for when the wimp wants it redrawn (hence the call to
  1138.     PROCshell_AttachUserRedraw). In both cases it is necessary just to
  1139.     replot the sprite.
  1140.  
  1141.     4.14 Complex Icons
  1142.  
  1143.     4.14.1 Bump Icons
  1144.  
  1145.     Bump icons are simply a pair of (usually!) arrow shaped icons that
  1146.     effect the value displayed in a third icon. The EvntShell library
  1147.     allows you to create this effect with one call to
  1148.     PROCshell_AttachBumpIconHandler.
  1149.  
  1150.     Note that clicking on a bump icon which ADJUST has the opposite effect
  1151.     to using SELECT, i.e. ADJUST on the decrement icon actually increases
  1152.     the value. This is normal RISC OS behaviour and is intended to avoid
  1153.     unnecessary mouse movements.
  1154.  
  1155.     See the !VBase2 demo application for an example of its use.
  1156.  
  1157.     4.15 Memory Management
  1158.  
  1159.     A crucial element of the EventShell library is the use of memory
  1160.     management routines originally published in Risc User magazine and used
  1161.     with permission. Many library routines require some memory workspace
  1162.     and they obtain this by calling FNshell_HeapBlockFetch(bytes_required)
  1163.     which returns the address of the allocated memory and release it when
  1164.     they are finished with PROCshell_HeapBlockReturn.
  1165.  
  1166.     This is vital for avoiding 'side effects' caused by using the same
  1167.     block of memory for different purposes as most WIMP programs tend to
  1168.     do. Equally important is the fact that as the routines are written in
  1169.     ARM code they are extremely fast.
  1170.  
  1171.     Another point to note is that this memory is claimed from the current
  1172.     wimp slot and not the RMA (Relocatable Module Area). This ensures that
  1173.     all of the memory claimed by the application is released back to the
  1174.     free pool when the application quits - this is not the case if memory
  1175.     is claimed from the RMA. It is only possible to reclaim RMA memory if
  1176.     the free space is at the top of the RMA which leads to the RMA
  1177.     allocation gradually growing as you run and quit applications.
  1178.  
  1179.     Unfortunately (in the authors view!) the MenuUtils module uses the RMA
  1180.     for storage of indirected data and menu structures. Hopefully this data
  1181.     gets put in any small available blocks so that the RMA allocation does
  1182.  
  1183.  
  1184.  
  1185.  
  1186.                                     Page 16
  1187.  
  1188.  
  1189.  
  1190.     
  1191.  
  1192.  
  1193.  
  1194.     EvntShell 2
  1195.     ________________________________________________________________________
  1196.  
  1197.  
  1198.     not increase.
  1199.  
  1200.     You are strongly advised to use the supplied memory management routines
  1201.     in the user application should you require storage for data, or
  1202.     temporary blocks for use with SWI calls for example. The time penalty
  1203.     for doing this is very small and in any case results in a more reliable
  1204.     and easier to maintain application.
  1205.  
  1206.     4.16 Error Handling
  1207.  
  1208.     The EvntShell library sets up a default error handler for you if you
  1209.     build the application with AppBuild. Since version 1.21 of the library
  1210.     support has been provided for Joe Taylor's !ThrowBack application which
  1211.     was on the September 1993 cover disk of Archimedes World. This traps
  1212.     errors in the program and opens a window showing the location and type
  1213.     of the error. Clicking on the error line then loads the file into your
  1214.     editor with the offending line highlighted which is a real timesaver.
  1215.  
  1216.     It is not necessary to have !ThrowBack, if it is not present a standard
  1217.     error window will pop up instead.
  1218.  
  1219.     The user application can generate errors on purpose as a way of
  1220.     aborting an operation. Control will then return to the wimp poll loop.
  1221.     This is done with a call to PROCshell_OK which opens an error box with
  1222.     a user defined message and an OK button.
  1223.  
  1224.     Also note that the MenuUtils module appears to set up its own error
  1225.     handler while calling the MenuSelect routine (the one you specify will
  1226.     be called when a selection is made for a particular menu item). This
  1227.     means that any errors in this routine appear to be ignored - in fact
  1228.     the routine just aborts at the error location without giving a message.
  1229.     This makes debugging these routines impossible unless you add the line:
  1230.  
  1231.     ON ERROR OFF
  1232.  
  1233.     at the start of the routine, i.e
  1234.  
  1235.     DEF FN_MenuSelect_TID(blk%)
  1236.     LOCAL str$
  1237.     ON ERROR OFF
  1238.     str$=$(blk%!12)
  1239.     PROCshell_IconPutData(newrec%,4,str$,TRUE)
  1240.     PROCget_entries(file_loc%,(blk%!0)+1)
  1241.     =0
  1242.     :
  1243.  
  1244.     4.17 Draw Files
  1245.  
  1246.     The standard method of creating and displaying vector graphics on Risc
  1247.     OS computers is the DrawFile, as created by the Acorn Draw application.
  1248.     It is also possible to create a DrawFile under program control using
  1249.     the routines in the supplied DrawLib library - this is seperate from
  1250.     the main shell library as the creation of DrawFiles is a specialised
  1251.     requirement.
  1252.  
  1253.  
  1254.  
  1255.  
  1256.                                     Page 17
  1257.  
  1258.  
  1259.  
  1260.     
  1261.  
  1262.  
  1263.  
  1264.     EvntShell 2
  1265.     ________________________________________________________________________
  1266.  
  1267.  
  1268.  
  1269.     A good example of the use of program generated DrawFiles would be the
  1270.     production of a graph which could be loaded into a DTP or word
  1271.     processing package. If you want to do something like this it makes
  1272.     sense to use the existing standard of DrawFiles, indeed if you want
  1273.     other applications to be able to load the data there is really no
  1274.     choice.
  1275.  
  1276.     EvntShell handles the creation of DrawFiles by creating the necessary
  1277.     data in memory (hence memory availability limits the size of DrawFile
  1278.     that can be created), first adding a 'pre-header' to the data. The
  1279.     purpose of the 'pre-header' is to store data such as the current
  1280.     drawing colour, the width of the lines etc without using global
  1281.     variables. Each DrawLib routine requires the address of the buffer
  1282.     holding the DrawFile, enabling several DrawFiles to be created in
  1283.     different buffers at the same time.
  1284.  
  1285.     Existing DrawFiles may be loaded, modified by the user application and
  1286.     re-saved. Full control is provided over line thicknesses, patterns, end
  1287.     caps, path and fill colours (stored as 24 bit values which RISC OS
  1288.     displays using dithering).
  1289.  
  1290.     DrawFiles can contain lines, boxes, circles, ellipses and outline font
  1291.     text at the moment which is not an exhaustive list but should suffice
  1292.     for most needs.
  1293.  
  1294.     An example of the use of the DrawLib routines is as follows:
  1295.  
  1296.     LIBRARY "EvntShell:Extensions.DrawLib"
  1297.     buffer% = 0 : REM Just declare the variable
  1298.     PROCshell_DrawCreateFile(buffer%)
  1299.     PROCshell_DrawBox(buffer%,100,100,25,25)
  1300.  
  1301.     which creates a DrawFile and then adds a square at the location x100
  1302.     y100 (relative to the bottom left of the paper) with sides 25mm long.
  1303.     By default millimetres are used for measurements, but drawing units may
  1304.     additionally be specified in centimeters, inches, OS units or points.
  1305.     Drawing units can be mixed within each file.
  1306.  
  1307.     A demonstration application called TestDraw should have been supplied
  1308.     with EvntShell to enable you to experiment.
  1309.  
  1310.     Note that as displaying a DrawFile uses Acorn's DrawFile module
  1311.     programs using it can only run on Risc OS 3 or later.
  1312.  
  1313.     4.18 OLE
  1314.  
  1315.     OLE is a technique whereby data can be sent from your application to be
  1316.     edited by another and reloaded when it is saved by the external
  1317.     application. The demo application OLE shows how this works.
  1318.  
  1319.     In addition the TestDraw application shows how a DrawFile can be sent
  1320.     to Draw for editing and how when the Draw window is closed the modified
  1321.     file is passed back for display.
  1322.  
  1323.  
  1324.  
  1325.  
  1326.                                     Page 18
  1327.  
  1328.  
  1329.  
  1330.     
  1331.  
  1332.  
  1333.  
  1334.     EvntShell 2
  1335.     ________________________________________________________________________
  1336.  
  1337.  
  1338.  
  1339.     5. The Tools
  1340.     ————————————
  1341.  
  1342.     Various programming tools have been written by myself and others to
  1343.     make producing wimp applications easier and faster. If you obtained the
  1344.     EvntShell library or updates thereof from the author you will have
  1345.     received all of the tools described here. If you obtained it from a PD
  1346.     library the author has little or no control over what else is supplied
  1347.     on the disk, so you may have to obtain the missing tools from other
  1348.     disks in the PD library, or better still send me a blank disk.
  1349.  
  1350.     Only one of the tools (one of the many Template editors available) is
  1351.     vital to the EvntShell Library, the others you can do without but they
  1352.     do make life easier.
  1353.  
  1354.     The following is a brief description of the tools supplied on APDL disk
  1355.     B122, and some other software which may be useful for developing
  1356.     applications
  1357.  
  1358.     5.1 !AppBuild
  1359.  
  1360.     Creates new application shells as 'stand alone' applications for
  1361.     distribution, or ones that depend on !EvntShell. You can specify a name
  1362.     for the application, and choose whether or not to make it 'Stand Alone'
  1363.     i.e if all the files required are copied into the new application
  1364.     directory. If it is not a stand alone application then modules, message
  1365.     files etc will be loaded from the !EvntShell directory.
  1366.  
  1367.     This application supports Acorn's !Help application.
  1368.  
  1369.     5.2 !ShellDBug
  1370.  
  1371.     A very simple debugger that displays trace output from the user
  1372.     application and the library code. Note that currently this application
  1373.     must be running before the application you want to debug.
  1374.  
  1375.     The EvntShell library outputs a commentary on what it is doing into a
  1376.     tracefile, providing that PROCshell_TraceInit and PROCshell_TraceOn
  1377.     have been called. The user application can also place output in this
  1378.     file using PROCshell_Tracef0.
  1379.  
  1380.     Outputting trace information will slow the user application noticeably,
  1381.     especially when starting up as a lot of trace info is generated by the
  1382.     call to PROCshell_ResourcesInit. Therefore it is best to only turn on
  1383.     tracing when necessary, and of course make sure that tracing is off on
  1384.     any applications you distribute!
  1385.  
  1386.     5.3 Other Tools
  1387.  
  1388.     There follows a brief description of some other
  1389.     PD/ShareWare/Copyrighted programs which I have found useful when
  1390.     developing EvntShell applications.
  1391.  
  1392.  
  1393.  
  1394.  
  1395.  
  1396.                                     Page 19
  1397.  
  1398.  
  1399.  
  1400.     
  1401.  
  1402.  
  1403.  
  1404.     EvntShell 2
  1405.     ________________________________________________________________________
  1406.  
  1407.  
  1408.     5.3.1 !BasShrink/!BasShrink_PD
  1409.  
  1410.     Is a BASIC program compressor which has been proved to work with
  1411.     EvntShell applications. !BasShrink_PD is Public Domain and available
  1412.     from various PD libraries, !BasShrink cost £5.00 and can be obtained
  1413.     from:
  1414.  
  1415.     John Wallace, Architype Software, 54 Parkes Hall Road, Woodsetton,
  1416.     Dudley, West Midlands, DY1 3SR ENGLAND
  1417.  
  1418.     See the section on compressing EvntShell programs for guidance on the
  1419.     options that can be used.
  1420.  
  1421.     5.3.2 !BLibII
  1422.  
  1423.     A BASIC Linker program available on APDL Disk B138. This builds a
  1424.     program from the user application and the EvntShell library containing
  1425.     only the routines that are actually needed. This is very useful for
  1426.     distributing the final application as !BLibII and !BasShrink used
  1427.     together will produce the minimum program size possible.
  1428.  
  1429.     Full instructions are provided with !BLibII, so I won't go into details
  1430.     here except to note that the ShellLib library already contains the
  1431.     extra information that !BLibII requires, although the conditional
  1432.     linking bits are not yet in place. This means that the linked program
  1433.     is bigger than it should be, but an improvement over just appending the
  1434.     library code to the end of the user application. This will improve in
  1435.     future releases.
  1436.  
  1437.     Note that you should use the ShellLib library for linking with BLibII
  1438.     because ShellLibRT has had the BLibII commands removed to save space.
  1439.  
  1440.     5.3.3 !TemplEd
  1441.  
  1442.     Also on APDL disk B138 this is I believe the best Template editor
  1443.     available anywhere. Forget !FormEd2 which was on some APDL B122 disks,
  1444.     !FormEd (Risc Squad version 2.84b on B053 or 2.87 also on B138) and any
  1445.     Acorn versions.
  1446.  
  1447.     5.3.4 !StrongEd
  1448.  
  1449.     A text editor which is now a ShareWare product again. The big advantage
  1450.     this has over any other editor is the accompanying !StrongHlp
  1451.     application as pressing F1 over a word in a program known to !StrongHlp
  1452.     causes an hypertext information window to open.
  1453.  
  1454.     The Archimedes World August 1993 cover disk contained a crippled
  1455.     version of !StrongEd (as the commercial version is known) which can be
  1456.     used for evaluation purposes, and this may be available from PD
  1457.     libraries. The PD/Demo version cannot create files and only allows two
  1458.     files to be open at any one time although this is not much of a problem
  1459.     for evaluation purposes.
  1460.  
  1461.     5.3.5 !StrongHlp
  1462.  
  1463.  
  1464.  
  1465.  
  1466.                                     Page 20
  1467.  
  1468.  
  1469.  
  1470.     
  1471.  
  1472.  
  1473.  
  1474.     EvntShell 2
  1475.     ________________________________________________________________________
  1476.  
  1477.  
  1478.                                        
  1479.     A hypertext type application which almost removes the need for the
  1480.     Reference Manuals. Files supplied with it detail most of the SWIs
  1481.     available and much more information is provided on BASIC, VDU calls,
  1482.     Filetypes etc. 
  1483.  
  1484.     The Archimedes World August 1993 cover disk also contained the PD
  1485.     version of !StrongHlp.
  1486.  
  1487.     The EvntShell library also has a few PROCs to interface with StrongHlp
  1488.     to enable user applications to register help systems.
  1489.  
  1490.     5.3.6 !ThrowBack
  1491.  
  1492.     This application appeared on the September 1993 cover disk of
  1493.     Archimedes World and is copyright that magazine. It provides a
  1494.     'throwback' window when an error occurs, and clicking on the throwback
  1495.     window opens your program editor at the line where the error occured.
  1496.     This is very useful when debugging a program.
  1497.  
  1498.     The EvntShell library contains the necessary support code for this.
  1499.     Note that for this to work properly you need the DDEUtils module and an
  1500.     editor that supports throwback (such as !DeskEdit or !StrongEd),
  1501.     although it will work after a fashion with !Edit as well.
  1502.  
  1503.     6. Distributing EvntShell Applications
  1504.     ——————————————————————————————————————
  1505.  
  1506.     It is probably best to copy ShellLibRT, ShellMsgs and the modules into
  1507.     your application directory, not forgetting to alter the !Run file and
  1508.     the LIBRARY statement in the runimage file to point to the new
  1509.     location. That way you are sure that all the necessary files are in one
  1510.     place for ease of copying.
  1511.  
  1512.     AppBuild will do this for you automatically if you drag the application
  1513.     to the
  1514.     iconbar icon, turn the 'Standalone' switch in the main window on and
  1515.     click OK.
  1516.                                         
  1517.     7. Debugging
  1518.     ————————————
  1519.  
  1520.     A simple debugger (!ShellDBug) is supplied with the library to display
  1521.     trace messages. You can also do wonders with a few VDU7 calls to check
  1522.     which parts of the application are actually being executed..
  1523.  
  1524.     8. The Credits
  1525.     ——————————————
  1526.  
  1527.     Quite a few people have been (however unwittingly) involved in this
  1528.     project such as:
  1529.  
  1530.     David Breakwell (the original idea), Robert Seago (for using it for
  1531.     things I wouldn't dream of attempting!), Cy Booker (various helpful
  1532.  
  1533.  
  1534.  
  1535.  
  1536.                                     Page 21
  1537.  
  1538.  
  1539.  
  1540.     
  1541.  
  1542.  
  1543.  
  1544.     EvntShell 2
  1545.     ________________________________________________________________________
  1546.  
  1547.  
  1548.     suggestions - I won't rewrite it in C or Assembler though - RISC-OS 3
  1549.     Documentation and the FontWindow module), Risc User magazine (for
  1550.     permission to use its heap manager code), Joris Röling (FontMenu
  1551.     module), Simon Huntingdon (Interface module), Alex Petrov (MenuUtils),
  1552.     Jan-Herman Buining (WASP application from which I worked out how to do
  1553.     RAM file transfers) and lastly the wife (Hilke) for putting up with me
  1554.     pounding away at a keyboard for hours when we could have been looking
  1555.     for new furniture instead.
  1556.  
  1557.     9. Future Enhancements
  1558.     ——————————————————————
  1559.  
  1560.     The software will become faster and be able to leap tall buildings with
  1561.     a single bound. Bugs and limitations will become fewer as well.
  1562.  
  1563.  
  1564.     - Support for automatic handling of more
  1565.       complicated icon types, for example
  1566.       sliders, rotating knobs etc
  1567.       (steady now don't get carried away)
  1568.     - Inclusion of more debugging aids
  1569.     - More drag types
  1570.     - Autoscroll handler when object is
  1571.       dragged within a window
  1572.     - Automatic handling of non-icon text
  1573.       within a window (like C txt objects)
  1574.     - Playing of Maestro tunes (ArchWay does!)
  1575.     - Extending message file useage to icons/
  1576.       windows/menus
  1577.     - Replay Films (!!!)
  1578.     - Better multiple file buffers
  1579.     - Complete German message files
  1580.     - Choice of message file language from
  1581.       within program
  1582.     - Automatic attaching of 'hot key' events
  1583.       by examining menu text
  1584.  
  1585.  
  1586.     10. Change History
  1587.     ——————————————————
  1588.  
  1589.     2.00    -       First release version 2
  1590.  
  1591.     2.01    -       Added documentation for interactive help routines
  1592.             -       Fixed MenuMaker routines
  1593.             -       Fixed OLE problems
  1594.  
  1595.     2.02    -       Added documentation for PROCshell_DrawSetPathNoColour
  1596.             -       Added documentation for PROCshell_DrawSetFillNoColour
  1597.             -       Added documentation for PROCshell_DrawDestroyFile
  1598.             -       Added documentation for PROCshell_DrawSetPathPattern
  1599.             -       Parameters changed for FNshell_MenuGetItemHandle
  1600.             -       Added routine PROCshell_AttachMenuHelpTag
  1601.  
  1602.  
  1603.  
  1604.  
  1605.  
  1606.                                     Page 22
  1607.  
  1608.  
  1609.  
  1610.     
  1611.  
  1612.  
  1613.  
  1614.     EvntShell 2
  1615.     ________________________________________________________________________
  1616.  
  1617.  
  1618.     2.03    -       Fixed bug concerning text under iconbar icons not being
  1619.                     updated when PROCshell_IconbarSetText was called
  1620.             -       Fixed bug with loading a file to a window or icon that
  1621.                     had no dataload event attached (possible address
  1622.                     exception error)
  1623.  
  1624.     2.04    -       Added routine FNshell_IconGetButtonType
  1625.             -       ClickSelect/ClickAdjust events no longer set the icon
  1626.                     button type to CLICK if the button type is already MENU
  1627.                     (so you can attach these events to icons that invert
  1628.                     when the pointer is over them)
  1629.  
  1630.     2.05    -       Width parameter for FNshell_IconBar now working again,
  1631.                     any amount of text can be placed under the iconbar icon
  1632.  
  1633.     2.06    -       Added routine PROCshell_WindowSendToBack
  1634.             -       PROCshell_WindowBringToTop now works on all windows
  1635.                     including those of the current task
  1636.  
  1637.     2.07    -       Added routine PROCshell_SpriteAreaInit
  1638.             -       Added routine PROCshell_SpriteLoad
  1639.             -       Added routine PROCshell_SpriteRemoveLeftWastage
  1640.             -       Added routine PROCshell_SpriteGetSize
  1641.             -       Added routine PROCshell_SpriteGetMode
  1642.             -       Added routine PROCshell_SpriteLoadAsDraw
  1643.             -       Added routine PROCshell_DrawSpriteArea
  1644.             -       Added routine FNshell_SpritesGetHeaderSize
  1645.  
  1646.     2.08    -       Fixed bug in FNshell_IconIsWritable
  1647.             -       Fixed bug in drag routines which resulted in problems
  1648.                     with draggable non writable icons
  1649.             -       Contents of draggable writable icons can be dragged to
  1650.                     other writables with the following effects :- normal
  1651.                     drag copies text from icon 1 to icon 2, overwriting the
  1652.                     contents of icon 2. SHIFT deletes the text from icon 1
  1653.                     (i.e. a move). CTRL appends the text from icon 1 to the
  1654.                     text of icon 2. SHIFT and CTRL can be used together.
  1655.                     (I'll probably get a visit from the Style Guide Police
  1656.                     over this one, but 'Personal Accounts 3' does something
  1657.                     similar and I think it's useful!)
  1658.             -       Added routine PROCshell_IconSetAllWritables
  1659.             -       Added routine PROCshell_IconClearAllWritables
  1660.             -       Added routine PROCshell_IconDisallowWritableDrags
  1661.             -       Added routine PROCshell_IconAllowWritableDrags
  1662.             -       Added routine PROCshell_WindowGetPosition
  1663.             -       Added routine PROCshell_PointerGetPosition
  1664.             -       Added routine PROCshell_PointerGetWindow
  1665.             -       Added routine PROCshell_PointerGetIcon
  1666.             -       Added routine PROCshell_WindowGetCentre
  1667.             -       Added routine PROCshell_PointerGetMovementVector
  1668.             -       Added routine PROCshell_PointerGetLastMovementVector
  1669.             -       Added routine PROCshell_PointerChangeShape
  1670.             -       Added routine PROCshell_PointerLimit
  1671.             -       Added routine PROCshell_PointerRemoveLimits
  1672.  
  1673.  
  1674.  
  1675.  
  1676.                                     Page 23
  1677.  
  1678.  
  1679.  
  1680.     
  1681.  
  1682.  
  1683.  
  1684.     EvntShell 2
  1685.     ________________________________________________________________________
  1686.  
  1687.  
  1688.             -       Added routine PROCshell_MouseRemoveLimits
  1689.             -       Added routine PROCshell_MenuTickAllItems
  1690.             -       Added routine PROCshell_MenuUntickAllItems
  1691.             -       Added routine PROCshell_MenuShadeAllItems
  1692.             -       Added routine PROCshell_MenuUnshadeAllItems
  1693.             -       Added routine FNshell_IconWritableDragStatus
  1694.             -       Added routine FNshell_WindowGetTopPaneDepth
  1695.             -       Added routine FNshell_WindowGetBottomPaneDepth
  1696.             -       Added routine FNshell_Evnts_DragIconStartIcon
  1697.             -       Added routine FNshell_Evnts_DragIconStartWindow
  1698.             -       Added routine FNshell_Evnts_WritableDragInProgress
  1699.             -       Added routine FNshell_PointerIsBelowWindowCentre
  1700.             -       Added routine FNshell_PointerIsAboveWindowCentre
  1701.             -       Added routine FNshell_PointerIsRightOfWindowCentre
  1702.             -       Added routine FNshell_PointerIsLeftOfWindowCentre
  1703.             -       Attaching ClickSelect and ClickAdjust events to an icon
  1704.                     now only changes the button type if the original type
  1705.                     was 'never'. This enables these events to be attached
  1706.                     to radio and option icons.
  1707.             -       Fixed bug in DragSave routines that was preventing solid
  1708.                     sprite dragging
  1709.             -       PROCshell_IconEnsureVisible now autoscrolls windows with
  1710.                     panes top and bottom correctly (it used to ignore
  1711.                     panes!)
  1712.             -       If a file icon is dragged from a static window the
  1713.                     window is not now automatically closed at the end of
  1714.                     the drag
  1715.             -       WindowClose event fixed and documentation corrected
  1716.             -       Bug in IconWatch handler fixed (returned "0" when
  1717.                     string in a text icon was "" )
  1718.             -       Added extension library ShareBan to handle ShareWare
  1719.                     banners
  1720.  
  1721.     2.09    -       Added routine PROCshell_PointerGetMouseButton
  1722.             -       Fixed bug in routine that loads the EvntData file
  1723.             -       Minor optimisations
  1724.             -       FNshell_InstallLib removed
  1725.  
  1726.     2.10    -       Bug fix to code that checks whether a valid name has
  1727.                     been entered in a file save window (problem with
  1728.                     multiple save dboxes only)
  1729.             -       Fixed bugs in PROCshell_MenuSortItems (was ignoring
  1730.                     start element number and generally not working at all).
  1731.                     Added default comparision routine for sorting menu text.
  1732.  
  1733.     2.11    -       Added routine FNshell_SliderGetHandle
  1734.             -       Corrected docs for PROCshell_AttachTaskInitialiseHandler
  1735.  
  1736.     2.12    -       Fixed bug in PROCshell_MenuShadeAllItems
  1737.             -       Fixed bug in FNshell_CalendarDaysInMonth (there's 31
  1738.                     days in January....)
  1739.  
  1740.     2.13    -       Fixed bug in FNshell_IconHasCaret (always returned
  1741.                     FALSE)
  1742.  
  1743.  
  1744.  
  1745.  
  1746.                                     Page 24
  1747.  
  1748.  
  1749.  
  1750.     
  1751.  
  1752.  
  1753.  
  1754.     EvntShell 2
  1755.     ________________________________________________________________________
  1756.  
  1757.  
  1758.             -       Fixed bug in PROCshell_IconPutData for writable icons
  1759.                     (caret was being placed at the end of the old icon
  1760.                     contents instead of the new contents)
  1761.             -       Added routine PROCshell_HidePane
  1762.             -       Added routine PROCshell_ShowPane
  1763.  
  1764.     2.14    -       Fixed various bugs in IconWatch event handling (wasn't
  1765.                     working at all..)
  1766.             -       Added docs for PROCshell_AttachSaveDesktopHandler
  1767.             -       Added docs for PROCshell_AttachDeskFontChangeHandler
  1768.             -       Added docs for PROCshell_AttachPointerEnteringWindow
  1769.                     Handler
  1770.             -       Added docs for PROCshell_AttachPointerLeavingWindow
  1771.                     Handler
  1772.  
  1773.     2.14a   -       Improved StrongHlp manual thanks to !StrongTst. No more
  1774.                     dangling links or unreachable pages (I hope..). Lots of
  1775.                     corrections to the ASCII documentation as well.
  1776.  
  1777.     2.15    -       Fixed bug in DataLoad routines (double click on a data
  1778.                     file belonging to the application loaded the app but
  1779.                     not the file).
  1780.             -       Added routine PROCshell_DrawSetJoinStyleNone
  1781.             -       Added routine PROCshell_DrawSetJoinStyleRound
  1782.             -       Added routine PROCshell_DrawSetJoinStyleBevelled
  1783.  
  1784.     2.16    -       Added routine PROCshell_WindowSetDefaultPosition
  1785.             -       Added routine PROCshell_WindowUserRedrawGetLines
  1786.             -       Added routine FNshell_MemLib_GetPageSize
  1787.             -       Added routine FNshell_MemLib_GetShellDynamicAreaNr
  1788.             -       Added routine FNshell_MemLib_GetShellDynamicAreaSize
  1789.             -       Added routine FNshell_MemLib_DynamicAreaAvailable
  1790.             -       Added routine FNshell_MemLib_GetShellDynamicTotalFree
  1791.             -       Added routine FNshell_MemLib_GetShellDynamicNrBlocks
  1792.             -       Added routine PROCshell_MenuPutTitle
  1793.             -       Fixed bug in icon dragging routines which meant that
  1794.                     solid sprite dragging had to be configured 'on' to
  1795.                     drag a file icon from a save dbox
  1796.  
  1797.  
  1798.  
  1799.  
  1800.  
  1801.  
  1802.  
  1803.  
  1804.  
  1805.  
  1806.  
  1807.  
  1808.  
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.  
  1815.                                     Page 25
  1816.